The Atari Compendium/The Atari Compendium (Toad Computers) (1994).iso/files/prgtools/programm.ing/progem.lzh/wind10.prf

Text File | 1987-06-23 | 12.9 KB | 300 lines

.!****************************************************************************
.!
.! ANTIC PUBLISHING INC., COPYRIGHT 1985.  REPRINTED BY PERMISSION.
.!
.! ** Professional GEM ** by Tim Oren
.!
.! Proff File by ST enthusiasts at
.! Case Western Reserve University
.! Cleveland, Ohio
.! uucp : decvax!cwruecmp!bammi
.! csnet: bammi@case
.! arpa : bammi%case@csnet-relay
.! compuserve: 71515,155
.!
.!****************************************************************************
.!
.!
.!****************************************************************************
.!
.!            Begin Part 10
.!
.!****************************************************************************
.!
.PART X VDI Graphics: Text Output
.PP
This  issue of ST PRO GEM concludes the two column series  on
VDI  with a look at simple VDI  text output,  and ways to optimize
its  speed.   There is also a Feedback section.   You may find the
associated  download  file under the name GMCL10.C in DL3  of  the
ATARI16 SIG (PCS-58).
.PP
To  keep  the size of this first discussion  of  text  within
reason, I am going to restrict it to use of the mono-spaced system
font   in  its  default  size  and  orientation.    Discussion  of
alternate and proportionally spaced fonts,  baseline rotation, and
character scaling will become a later article in this series.
.SH DEFINITIONS
This  article  makes use of  some  terminology
which may be unfamiliar if you have not used digital typefaces.  A
mono-spaced  font  is  one in which  each  character  occupies  an
identically  wide  space on the screen.   A proportional font  has
characters  which occupy different widths.   For instance,  an 'l'
would probably be narrower than a 'w'.
.PP
Text may be "justified" right,  left,  or center.  This means
that  the right character,  left character,  or center position of
the  text  string is constrained to a given location.   In  common
usage,  a  page  of text is "ragged right" if its lines  are  left
justified only.   The text page is "fully justified",  "justified"
or  (ambiguously)  "right justified" if BOTH the  left  and  right
characters are contrained to fixed columns.  Full justification is
produced  by  inserting extra blank characters in the  case  of  a
mono-spaced font,  or by adding extra pixel columns in the case of
proportional output.
.PP
A  text character (in a monospaced font) is written inside  a
standard sized cell or box.  Vertically, the cell extends from the
"top  line" down to the "bottom line".   If there are one or  more
blank  lines at the top or bottom,  they are called "leading"  and
are  used  to separate lines of text.   The characters  themselves
always  fall between the "ascent line",  which is the highest line
reached by characters such as 'd' and 'l', and the "descent line",
which  is the lowest line in characters like 'q' and  'g'.   Other
locations  of  interest are the "half line",  which is the top  of
characters  like  'a' or 'n',  and the "base line",  which is  the
bottom of characters which do not have descenders.
.PP
Before  plunging into the Attribute Functions for  text,  you
should  note  that  the  writing  mode  (vswr_mode)  and  clipping
rectangle  (vs_clip) attributes discussed in the last column  (#9)
also  pertain  to  text.   Since much of the  discussion  of  text
optimization  will  center on these attributes,  you may  want  to
review them.
.SH TEXT ATTRIBUTES
The writing color for graphics text is set
with the command:
.FB vst_color()
          vst_color(vdi_handle, color);
.FE
Vdi_handle  is  always the handle returned from  graf_handle()  at
application startup.  Color is a word value between 0 and 15 which
designates  the  output  color index.   As discussed  in  previous
columns,  the  actual  color  which appears is  dependent  on  the
current  palette  settings.   In  applications such  as  word  and
outline  processors  it  is important that  characters  and  their
background  provide  good contrast to avoid eyestrain.   In  these
situations,  you  may  want to use the setPalette and/or  setColor
XBIOS  functions  to  force the palette to a  known  state  before
starting the application.
.PP
You  can choose a variety of special output effects for  your
text with the call:
.FB vst_effects()
vst_effects(vdi_handle, effects);
.FE
Effects is a single flag word,  with the bits having the following
significance:
.BO
0 - Thicken
.EO
.BO
1 - Lighten
.EO
.BO
2 - Skew
.EO
.BO
3 - Underline
.EO
.BO
4 - Outline
.EO
.BO
5 - Shadow
.EO
.PP
In each case,  turning the bit on selects the effect.   Otherwise,
the  effect  is  off.   Any  number of  multiple  effects  may  be
selected, but the result may not always be pleasing or legible.
.PP
The  "thicken"  effect widens the character  strokes  by  one
pixel,   resulting  in  the  appearance  of  boldface  type.   The
"lighten" effect superimposes a half-tone dither on the character.
This mode is useful for indicating non-selectable text items,  but
is not legible enough for other purposes.
.PP
The  skew effect shifts the rows of the character the  right,
with  the greatest displacement at the top.   This results in  the
appearance of italic text.   You should be aware that the VDI does
not  compensate for this effect.   This means that a skewed italic
character which is immediately followed by a normal blank will  be
overstruck,  and  part of the top of the character will disappear.
Likewise,  a  skewed character written to the left of an  existing
normal  character will overstrike part of it.   There is a related
bug  in  the VDI clipping logic which may cause some  parts  of  a
skewed  character not to be redrawn if they fall at the edge of  a
clipping  rectangle,  even  though  they should  fall  within  the
region.
.PP
The  outline  effect  produces output which is  a  one  pixel
"halo" around the normal character.  The shadow effect attempts to
create  a  "drop  shadow" to the side  of  the  character.   These
effects  should be used very sparingly with default  sized  fonts.
They often result in illegible output.
.PP
When  graphics text is written,  a screen coordinate must  be
specified  for  the output.   The relationship of the text to  the
screen point is determined by the call:
.FB bst_alignment()
          vst_alignment(vdi_handle, hin, vin, &hout, &vout);
.FE
Hin  and  vin are each words,  with values specifying the  desired
horizontal  and vertical alignment,  respectively.   Hout and vout
receive the actual values set by the VDI.  If they differ from the
requested values, an error has occurred.
.PP
Hin may be set to zero for left justification, one for center
justification,  or  two  for right justification.   The coordinate
given when text is written becomes the "anchor point" as described
in the definitions above.  The default justification is left.
.PP
Vin determines what reference line of the text is  positioned
at the output coordinate.  The selection values are:
.bp
.BO
0 - baseline (default)
.EO
.BO
1 - half line
.EO
.BO
2 - ascent line
.EO
.BO
3 - bottom line
.EO
.BO
4 - descent line
.EO
.BO
5 - top line
.EO
.PP
A  common combination of alignments is left (0) and top  line
(5).   This  mode guarantees that all text output will lie to  the
right and below the output coordinate.   This corresponds with the
AES object and GRECT coordinate systems.
.PP
Finally, the call to do the actual output is:
.FB v_gtext()
v_gtext(vdi_handle, x, y, string);
.FE
X  and y define the screen coordinate to be used as the  alignment
point.   String  is  a pointer to a null terminated string,  which
must  be total eighty characters or less,  exclusive of the  null.
This limit is imposed by the size of the intin[] array in the  VDI
binding.   Be  warned  that  it  is NOT checked  in  the  standard
binding!  Exceeding it may cause memory to be overwritten.
.PP
One Inquire Function is useful with text output.  The call
.FB vqt_attributes()
vqt_attributes(vdi_handle, attrib);
.FE
reads  back the current attribute settings into the 10 word  array
attrib[].   The  main  items  of interest  are  attrib[6]  through
attrib[9],  which contain the width and height of characters,  and
the  width and height of the character cell in the  current  font.
You  should  rely  on this function to  obtain  size  information,
rather  than using the output of the graf_handle()  function.   On
the ST, graf_handle() always returns sizes for the monochrome mode
system font, which will be incorrect in the color screen modes.
.PP
Attrib[1] will contain the current graphics text color as set
by  vst_color().   Attrib[3]  and [4] contain the  horizontal  and
vertical alignment settings, respectively.  Attrib[5] contains the
current writing mode, as set by vswr_mode().
.SH OPTIMIZATION
The most common complaint about using bit maps
for character output is lack of speed.  This section suggests ways
to  speed  things up.   By adopting all of these methods,  you can
realize an improvement of two to three times in speed.
.SH BYTE ALIGNMENT
Since writing graphic text is essentially a
bit-blit operation,  characters which have "fringes",  that is, do
not  align  evenly with byte boundaries,  will suffer  performance
penalities.  The default system fonts in all resolutions of the ST
are  a  multiple of eight pixels wide,  so the problem reduces  to
assuring  that  each characters starts at a byte boundary  in  the
screen bit map.  This will be true if the horizontal pixel address
of the left edge of the character is evenly divisible by eight.
.PP
Obviously,  byte  alignment  is easiest to enforce  when  the
horizontal justification is right or left.  Doing so with centered
text is possible, but requires adding padding blanks to odd length
strings.
.PP
When  writing  text within windows,  it is helpful to  assure
that the edges of the window working area are byte aligned.  There
is  a section of code in the download which shows a technique  for
converting  a  user requested window position and/or size  to  its
working   dimensions,   byte-aligning  the  width  and  horizontal
position, and computing the adjusted external window coordinates.
.SH WRITING MODE
The fastest text output mode is replace.  All
other modes require reading in the target raster area and  merging
it  with  the  new information.   You may find that you  must  use
transparent or reverse transparent mode,  for instance,  to use or
preserve an underlying background color other than white.  In this
case,  you  can  still  do  some optimization by  filling  in  the
background color for the entire string with a v_bar() call, rather
than doing it one character cell at a time.
.SH CLIPPING
VDI  output  always  proceeds  faster  when  the
clipping rectangle is turned off, and text output is no exception.
Remember  that  you  may only do this if you are  drawing  into  a
dialog box,  or into the interior of a window which you know is on
top.   (You  can  use  the WM_TOPPED and  WM_NEWTOP  messages  for
keeping track of the top window, or use the WF_TOP wind_get() call
to  find the current top.)  In both of these cases,  you will know
the  width  of the drawing area,  and you can truncate the  output
string to fit exactly, rather than setting the clipping rectangle.
For this to work,  you must have used the byte alignment technique
to  assure  that the width of the writing area is  a  multiple  of
eight.
.SH BINDINGS
The  normal binding for v_gtext() is inefficient.
It copies the string which you supply character-by-character  into
intin[] before it calls the VDI itself.  In many cases, it will be
more  efficient for your application to place characters  directly
into  intin[] and make the VDI trap call directly.   To give you a
start,  the  code  for  the standard v_gtext()  binding  has  been
included in the download.  When setting up intin[], be sure not to
load  more  than  80 characters,  or you will probably  crash  the
system!
.SH MOVING TEXT
When performing text editing on the screen, you
should  avoid rewriting the string under edit  whenever  possible.
It is always more efficient to use the raster operations to move a
string  to  the right or left,  assuming that you have obeyed  the
byte  alignment rule.    If you are deleting characters,  blit the
unchanged part of the screen to the left,  and overstrike the last
character  in the string with a blank.   If inserting  characters,
blit  the  trailing  portion of the string  to  the  right  before
writing in the new character.
.SH THAT'S IT FOR NOW
This concludes the two article series on
simple  VDI output.   Future columns may explore more complex  VDI
topics such as proportional text.  If there is something you would
like  to  see,  please  use the Online Feedback to  let  me  know!
Meanwhile,  the next column will give out the locations of some of
the  "hooks" and "trapdoors" built into the AES object  structure,
including  how  to set up user-defined AES drawing  objects.
.!
.!
.!*****************************************************************************
.!*                                          *
.!*                End Part 10                      *
.!*                                          *
.!*****************************************************************************